home *** CD-ROM | disk | FTP | other *** search
/ Cream of the Crop 1 / Cream of the Crop 1.iso / EDUCATE / VCLANG11.ARJ / VC.DOC < prev    next >
Text File  |  1991-06-12  |  11KB  |  282 lines
  1.  
  2.            VisiCLANG  --  A Visible Compiler for CLANG
  3.            ===========================================
  4.            v1.10  (C)Copyright 1990, Univ. of Limerick
  5.  
  6. INTRODUCTION
  7. ------------
  8.  
  9. VisiCLANG is a tool to aid one in understanding the inner
  10. workings of a compiler. It does this by allowing the user to
  11. trace all aspects of a compiler's execution as it is compiling
  12. the user's own program(s). Assembly language code is generated by
  13. the compiler and then executed on an stack machine implemented in
  14. software.
  15.  
  16. CLANG is a simple teaching language developed by P.D. Terry and
  17. described by him as a "superset of a subset of Pascal". It limits
  18. it's data types to integers and arrays of integers, but includes
  19. data abstraction and concurrency. The CLANG compiler uses straight-
  20. forward recursive-descent parsing implemented in "highly standard
  21. Pascal".
  22.  
  23. CLANG (and the stack machine) is developed and explained in the
  24. book "Programming Language Translation" by P.D. Terry (Addison-
  25. Wesley, 1986). Level 5 of CLANG is used in VisiCLANG, and the
  26. source code corresponds exactly with the listing given by Terry
  27. in his book (pp. 379-411 ... or it can be written to a file from
  28. within VisiCLANG). We recommend Terry's book for in-depth study
  29. of CLANG and/or the stack machine. See also SIGPLAN Notices V25
  30. #8, August 1990, for a general description of the compiler.
  31.  
  32. (A version of VisiCLANG for Level 2 of CLANG is also available;
  33. contact the authors for more information.)
  34.  
  35. MODES OF OPERATION
  36. ------------------
  37.  
  38. There are two distinct modes of operation for VisiCLANG: compile
  39. mode and execute mode. Compile mode allows the user to view a
  40. program being compiled and, if compilation is successful, to save
  41. the resultant code; execute mode allows the user to view the com-
  42. piled program being executed on the stack machine (SM). Both
  43. modes can be used independently of the other -- you need not
  44. execute your compiled program and you can execute previously
  45. saved SM code without re-compiling the source.
  46.  
  47. RUNNING VisiCLANG
  48. -----------------
  49.  
  50. Usage: vc [options]
  51.  where options are:
  52.    <file>     -- select compile mode and input CLANG file
  53.    /e[<file>] -- select execute mode and input SM code file
  54.    /h         -- help
  55.  
  56.  (anything delimited by [ ] denotes an optional part of a
  57.   command)
  58.  
  59. Note: Use `vc2' instead of `vc' if you have VisiCLANG for Level 2 of CLANG.
  60.  
  61. COMPILE MODE
  62. ------------
  63.  
  64. When first entering Compile Mode the user is prompted for the
  65. name of an input file. This is the CLANG program which is to be
  66. compiled, and it is used for all subsequent operations unless the
  67. user specifies otherwise.
  68.  
  69. There are six primary windows in compile mode. These are:
  70.  
  71.    CLANG     Shows CLANG compiler source code, with the line
  72.              about to be executed highlighted.
  73.  
  74.    Input     Shows the user's CLANG source code file as seen by
  75.              the compiler -- one line at a time is read into a
  76.              buffer and then an arrow in the window indicates
  77.              exactly where the lexical analyzer is scanning in
  78.              the buffer.
  79.  
  80.    Code      Shows the SM code as it is generated.
  81.  
  82.    Grammar   Shows the trace through the CLANG grammar as it's
  83.              compiling your code. A parse tree can be built by
  84.              following highlighted elements down through the
  85.              window. The meta-language used is slightly modified
  86.              EBNF:
  87.  
  88.               (1) The meta-symbols < > are used to denote non-
  89.                   terminals (exception: the relational
  90.                   operators).
  91.               (2) The symbol ::= should be read "is defined as"
  92.               (3) The vertical bar | should be read "or"
  93.               (4) Curly braces { } are used to denote repetition
  94.                   of a string 0 or more times.
  95.               (5) Square brackets [ ] are used to denote an
  96.                   optional item.
  97.               (6) The meta-symbols << >> are used to denote
  98.                   certain terminals.
  99.               (7) Null productions are indicated by NULL.
  100.               (8) Symbols and words with none of the above punc-
  101.                   tuation are terminals.
  102.  
  103.    Procedure
  104.    List      Traces the calls to procedures in the parser that
  105.              correspond to non-terminals in the grammar
  106.  
  107.    Variable  This is a pop-up window that allows the user to
  108.              watch any of the compiler's variables (with the
  109.              hopefully obvious restriction that you are current-
  110.              ly executing within the scope of the variable you
  111.              wish to watch).
  112.  
  113.  
  114. EXECUTE MODE
  115. ------------
  116.  
  117. If execute mode is entered immediately after a successful
  118. compilation, the code generated by the previous compilation will
  119. be executed. Otherwise the user is prompted for the name of a
  120. code file.
  121.  
  122.  Execute mode has seven main windows:
  123.  
  124.    CLANG    As with Compile mode, shows the CLANG source, with
  125.             the line about to execute highlighted.
  126.  
  127.    Input/
  128.    Output   I/O window for program currently executing.
  129.  
  130.    Code     The complete SM program listing, with the next
  131.             instruction to be executed highlighted.
  132.  
  133.    Stack    Shows the SM's stack (with the first column being the
  134.             address, column 2 the contents). The base and top-of-
  135.             stack "pointers" are indicated with appropriate
  136.             symbols.
  137.  
  138.    Display  CLANG uses a display to handle variable addressing;
  139.             this window shows the current state of this display.
  140.  
  141.    Source   Shows a traces through the CLANG source as the
  142.             program is being executed; this window is not active
  143.             if you are executing SM code that has been directly
  144.             loaded in from a file.
  145.  
  146.    Variable (Same as in compile mode)
  147.  
  148. COMMANDS
  149. --------
  150.  
  151. The following function keys can be used in either mode:
  152.  
  153.      F1  Help
  154.      F2  Search (searches for a string in the CLANG compiler
  155.          source)
  156.      F3  Goto line (in the CLANG compiler source code)
  157.      F4  Goto start (begin compiling your CLANG or SM source
  158.          program; necessary only if you wish to re-start compila-
  159.          tion/execution)
  160.      F5  New source file (choose a different CLANG/SM source
  161.          program & begin compilation/execution)
  162.      F6  Variables window (selects the variables window; user
  163.          will be prompted to add a variable if none have yet been
  164.          chosen)
  165.      F7  Cycle windows (cycles through screen windows; a window
  166.          must be selected before it is modified, with double-line
  167.          borders indicating the currently selected window.)
  168.      F8  Modify window (allows you to modify (move,resize,etc.)
  169.          the currently selected window)
  170.      F9  Switch modes (switches between compile & execute modes)
  171.     F10  Main menu
  172.  
  173.  
  174. VisiCLANG allows you to watch different aspects of the compila-
  175. tion/execution process at different rates as you step through
  176. source code. The following keys can be used in this process:
  177.  
  178.             (CM -- compile mode; EM -- execute mode)
  179.  
  180. <space bar>   Single step through the CLANG compiler(CM) or
  181.               interpreter(EM) source code
  182.           B   Go until breakpoint; pressing B with no breakpoints
  183.               will cause VisiCLANG to attempt to compile(CM) or
  184.               execute(EM) your entire program
  185.           C   Go until code generated (CM) or executed(EM);
  186.               (CM -- compilation will continue until the next SM
  187.               instruction is generated; EM -- will single-step
  188.               you through the SM code)
  189.           G   Go until grammar change; compilation will continue
  190.               until the grammar window is updated (CM only)
  191.           T   Go until next token; compilation will continue
  192.               until the next token is returned by the lexical
  193.               analyzer (CM only)
  194.           P   CM -- Go until procedure end; compilation continues
  195.                     until you reach the end of the last procedure
  196.                     listed in the Procedure List window
  197.               EM -- Show process list (if applicable)
  198.  
  199.           >   Add breakpoint; places a breakpoint on the current
  200.               line (the one highlighted) in the CLANG com-
  201.               piler(CM) or interpreter(EM) source.
  202.           <   Clear breakpoint; removes the breakpoint on the
  203.               current line in the CLANG compiler(CM) or inter-
  204.               preter(EM) source.
  205.           A   Clear all breakpoints (in the CLANG compiler(CM) or
  206.               interpreter(EM) source)
  207.  
  208.      V or +  Add variable; prompts you for the name and then
  209.              adds a variable to the variable watch window
  210.           -  Delete variable; deletes highlighted variable from
  211.              the watch variable window; variables can be high-
  212.              lighted by first selecting the variable window (F6)
  213.              and then using the up/down arrow keys
  214.           H  Hide variable window; "hides" or closes variable
  215.              window (note that F6 will re-open it)
  216.           Z  Zap variable window; removes all variables from
  217.              variable window
  218.           S  Show symbol table (CM only)
  219.  
  220.     <Ctrl>L  Repeat last search (initial search done with F2)
  221.           F  Trace CLANG toggle; when on, the next line to be
  222.              executed in the CLANG compiler(CM) or interpreter
  223.              (EM) will be highlighted (turning Trace off will
  224.              noticeable speed up VisiCLANG)
  225.           K  Pause on token toggle; when on, VisiCLANG will pause
  226.              whenever a token has been recognized (CM only)
  227.           D  Set Delay; allows you to control the speed at which
  228.              the compiler will run (delays are inserted after
  229.              each line of CLANG executed)
  230.  
  231.           Q  Quit VisiCLANG
  232.  
  233.  
  234. The following keys are available whenever a scrolling window has
  235. been selected:
  236.  
  237.   <up arrow>/<down arrow>  Scroll up/down one line
  238.   <PgUp>/<PgDn>            Scroll up/down one screen
  239.   <Home>/<End>             Scroll to start/end of window
  240.  
  241. Note that if a window is too small to show an entire line, the
  242. size of the window can be modified using F8.
  243.  
  244.  
  245. FILES ON DISK
  246. -------------
  247.  
  248. read.me    special instructions
  249. vc*.exe    VisiCLANG executable
  250. vc*.ov*    VisiCLANG overlay files (do not delete!)
  251. vc*.cfg    VisiCLANG configuration file (stores status of
  252.            VisiCLANG upon exit from program; deletion or renaming
  253.            will cause VisiCLANG to begin with default set-up)
  254. vc.doc     this document
  255. *.cln      CLANG source code files
  256. *.cod      SM source code files
  257.  
  258.  
  259. TERMS AND CONDITIONS OF USE
  260. ---------------------------
  261.  
  262. YOU MAY FREELY COPY AND DISTRIBUTE VERBATIM COPIES OF VISICLANG
  263. AS LONG AS YOU ALSO DISTRIBUTE ALL COPYRIGHT NOTICES AND DIS-
  264. CLAIMERS OF WARRANTY. THE PROGRAM IS DISTRIBUTED "AS IS" WITHOUT
  265. WARRANTY OF ANY KIND -- THE ENTIRE RISK AS TO THE QUALITY AND
  266. PERFORMANCE OF THE SOFTWARE IS WITH THE USER. WHILE WE ENCOURAGE
  267. ANY FEEDBACK AND SUGGESTIONS, FUTURE SUPPORT OF THIS PRODUCT BY
  268. THE AUTHORS OR THE UNIVERSITY IS NOT GUARANTEED.
  269.  
  270.  
  271. Any comments/suggestions/gripes? Here's our address:
  272.  
  273. Dan Resler
  274. Keith O'Sullivan
  275. Dept. of Electronics & Computer Engineering,
  276. University of Limerick,
  277. Limerick, Ireland
  278.  
  279. email: reslerd@ul.ie
  280. phone: Ireland 061-333644
  281. fax  : Ireland 061-330316
  282.